home *** CD-ROM | disk | FTP | other *** search
/ Amiga Plus Leser 15 / Amiga Plus Leser CD 15.iso / Tools / Development / MosaicSRC / libwww2 / HTAAUtil.h < prev    next >
Encoding:
C/C++ Source or Header  |  2002-03-13  |  10.6 KB  |  337 lines
  1. /*                                            Utilities for the Authorization parts of libwww
  2.              COMMON PARTS OF AUTHORIZATION MODULE TO BOTH SERVER AND BROWSER
  3.                                              
  4.    This module is the interface to the common parts of Access Authorization (AA) package
  5.    for both server and browser. Important to know about memory allocation:
  6.    
  7.    Routines in this module use dynamic allocation, but free automatically all the memory
  8.    reserved by them.
  9.    
  10.    Therefore the caller never has to (and never should) free() any object returned by
  11.    these functions.
  12.    
  13.    Therefore also all the strings returned by this package are only valid until the next
  14.    call to the same function is made. This approach is selected, because of the nature of
  15.    access authorization: no string returned by the package needs to be valid longer than
  16.    until the next call.
  17.    
  18.    This also makes it easy to plug the AA package in: you don't have to ponder whether to
  19.    free() something here or is it done somewhere else (because it is always done somewhere
  20.    else).
  21.    
  22.    The strings that the package needs to store are copied so the original strings given as
  23.    parameters to AA functions may be freed or modified with no side effects.
  24.    
  25.    Also note: The AA package does not free() anything else than what it has itself
  26.    allocated.
  27.    
  28.  */
  29.  
  30. #ifndef HTAAUTIL_H
  31. #define HTAAUTIL_H
  32.  
  33. #include "HTUtils.h"            /* BOOL, PARAMS, ARGS */
  34. #include "HTList.h"
  35. #include "tcp.h"
  36.  
  37. #ifdef SHORT_NAMES
  38. #define HTAASenu        HTAAScheme_enum
  39. #define HTAASnam        HTAAScheme_name
  40. #define HTAAMenu        HTAAMethod_enum
  41. #define HTAAMnam        HTAAMethod_name
  42. #define HTAAMinL        HTAAMethod_inList
  43. #define HTAAteMa        HTAA_templateMatch
  44. #define HTAAmaPT        HTAA_makeProtectionTemplate
  45. #define HTAApALi        HTAA_parseArgList
  46. #define HTAAsuRe        HTAA_setupReader
  47. #define HTAAgUfL        HTAA_getUnfoldedLine
  48. #endif /*SHORT_NAMES*/
  49.  
  50.  
  51. /*
  52.  
  53. Default filenames
  54.  
  55.  */
  56. #ifndef PASSWD_FILE
  57. #define PASSWD_FILE     "/home2/luotonen/passwd"
  58. #endif
  59.  
  60. #ifndef GROUP_FILE
  61. #define GROUP_FILE      "/home2/luotonen/group"
  62. #endif
  63.  
  64. #define ACL_FILE_NAME   ".www_acl"
  65.  
  66.  
  67. /*
  68. ** Numeric constants
  69. */
  70. #define MAX_USERNAME_LEN        128      /* @@ Longest allowed username    */
  71. #define MAX_PASSWORD_LEN        3*13    /* @@ Longest allowed password    */
  72.                                         /* (encrypted, so really only 3*8)*/
  73. #define MAX_METHODNAME_LEN      128      /* @@ Longest allowed method name */
  74. #define MAX_FIELDNAME_LEN       128      /* @@ Longest field name in       */
  75.                                         /* protection setup file          */
  76. #define MAX_PATHNAME_LEN        128      /* @@ Longest passwd/group file   */
  77.                                         /* patname to allow               */
  78.  
  79. /*
  80. ** Helpful macros
  81. */
  82. #define FREE(x) if (x) {free(x); x=NULL;}
  83.  
  84. /*
  85.  
  86. Datatype definitions
  87.  
  88.   HTAASCHEME
  89.   
  90.    The enumeration HTAAScheme represents the possible authentication schemes used by the
  91.    WWW Access Authorization.
  92.    
  93.  */
  94.  
  95. typedef enum {
  96.     HTAA_UNKNOWN,
  97.     HTAA_NONE,
  98.     HTAA_BASIC,
  99.     HTAA_PUBKEY,
  100.     HTAA_KERBEROS_V4,
  101.     HTAA_KERBEROS_V5,
  102. #ifdef PEM_AUTH
  103.     HTAA_PEM,
  104.     HTAA_PGP,
  105. #endif /* PEM_AUTH */
  106.     HTAA_MAX_SCHEMES /* THIS MUST ALWAYS BE LAST! Number of schemes */
  107. } HTAAScheme;
  108.  
  109. /*
  110.  
  111.   ENUMERATION TO REPRESENT HTTP METHODS
  112.   
  113.  */
  114.  
  115. typedef enum {
  116.     METHOD_UNKNOWN,
  117.     METHOD_GET,
  118.     METHOD_PUT
  119. } HTAAMethod;
  120.  
  121. /*
  122.  
  123. Authentication Schemes
  124.  
  125.  */
  126.  
  127. /* PUBLIC                                               HTAAScheme_enum()
  128. **              TRANSLATE SCHEME NAME TO A SCHEME ENUMERATION
  129. ** ON ENTRY:
  130. **      name            is a string representing the scheme name.
  131. **
  132. ** ON EXIT:
  133. **      returns         the enumerated constant for that scheme.
  134. */
  135. PUBLIC HTAAScheme HTAAScheme_enum PARAMS((CONST char* name));
  136.  
  137.  
  138. /* PUBLIC                                               HTAAScheme_name()
  139. **                      GET THE NAME OF A GIVEN SCHEME
  140. ** ON ENTRY:
  141. **      scheme          is one of the scheme enum values:
  142. **                      HTAA_NONE, HTAA_BASIC, HTAA_PUBKEY, ...
  143. **
  144. ** ON EXIT:
  145. **      returns         the name of the scheme, i.e.
  146. **                      "none", "basic", "pubkey", ...
  147. */
  148. PUBLIC char *HTAAScheme_name PARAMS((HTAAScheme scheme));
  149.  
  150. /*
  151.  
  152. Methods
  153.  
  154.  */
  155.  
  156. /* PUBLIC                                                   HTAAMethod_enum()
  157. **              TRANSLATE METHOD NAME INTO AN ENUMERATED VALUE
  158. ** ON ENTRY:
  159. **      name            is the method name to translate.
  160. **
  161. ** ON EXIT:
  162. **      returns         HTAAMethod enumerated value corresponding
  163. **                      to the given name.
  164. */
  165. PUBLIC HTAAMethod HTAAMethod_enum PARAMS((CONST char * name));
  166.  
  167.  
  168. /* PUBLIC                                               HTAAMethod_name()
  169. **                      GET THE NAME OF A GIVEN METHOD
  170. ** ON ENTRY:
  171. **      method          is one of the method enum values:
  172. **                      METHOD_GET, METHOD_PUT, ...
  173. **
  174. ** ON EXIT:
  175. **      returns         the name of the scheme, i.e.
  176. **                      "GET", "PUT", ...
  177. */
  178. PUBLIC char *HTAAMethod_name PARAMS((HTAAMethod method));
  179.  
  180.  
  181. /* PUBLIC                                               HTAAMethod_inList()
  182. **              IS A METHOD IN A LIST OF METHOD NAMES
  183. ** ON ENTRY:
  184. **      method          is the method to look for.
  185. **      list            is a list of method names.
  186. **
  187. ** ON EXIT:
  188. **      returns         YES, if method was found.
  189. **                      NO, if not found.
  190. */
  191. PUBLIC BOOL HTAAMethod_inList PARAMS((HTAAMethod        method,
  192.                                      HTList *           list));
  193. /*
  194.  
  195. Match Template Against Filename
  196.  
  197.  */
  198.  
  199. /* PUBLIC                                               HTAA_templateMatch()
  200. **              STRING COMPARISON FUNCTION FOR FILE NAMES
  201. **                 WITH ONE WILDCARD * IN THE TEMPLATE
  202. ** NOTE:
  203. **      This is essentially the same code as in HTRules.c, but it
  204. **      cannot be used because it is embedded in between other code.
  205. **      (In fact, HTRules.c should use this routine, but then this
  206. **       routine would have to be more sophisticated... why is life
  207. **       sometimes so hard...)
  208. **
  209. ** ON ENTRY:
  210. **      template        is a template string to match the file name
  211. **                      agaist, may contain a single wildcard
  212. **                      character * which matches zero or more
  213. **                      arbitrary characters.
  214. **      filename        is the filename (or pathname) to be matched
  215. **                      agaist the template.
  216. **
  217. ** ON EXIT:
  218. **      returns         YES, if filename matches the template.
  219. **                      NO, otherwise.
  220. */
  221. PUBLIC BOOL HTAA_templateMatch PARAMS((CONST char * template,
  222.                                        CONST char * filename));
  223.  
  224.  
  225. /* PUBLIC                                       HTAA_makeProtectionTemplate()
  226. **              CREATE A PROTECTION TEMPLATE FOR THE FILES
  227. **              IN THE SAME DIRECTORY AS THE GIVEN FILE
  228. **              (Used by server if there is no fancier way for
  229. **              it to tell the client, and by browser if server
  230. **              didn't send WWW-ProtectionTemplate: field)
  231. ** ON ENTRY:
  232. **      docname is the document pathname (from URL).
  233. **
  234. ** ON EXIT:
  235. **      returns a template matching docname, and other files
  236. **              files in that directory.
  237. **
  238. **              E.g.  /foo/bar/x.html  =>  /foo/bar/ *
  239. **                                                  ^
  240. **                              Space only to prevent it from
  241. **                              being a comment marker here,
  242. **                              there really isn't any space.
  243. */
  244. PUBLIC char *HTAA_makeProtectionTemplate PARAMS((CONST char * docname));
  245. /*
  246.  
  247. MIME Argument List Parser
  248.  
  249.  */
  250.  
  251.  
  252. /* PUBLIC                                               HTAA_parseArgList()
  253. **              PARSE AN ARGUMENT LIST GIVEN IN A HEADER FIELD
  254. ** ON ENTRY:
  255. **      str     is a comma-separated list:
  256. **
  257. **                      item, item, item
  258. **              where
  259. **                      item ::= value
  260. **                             | name=value
  261. **                             | name="value"
  262. **
  263. **              Leading and trailing whitespace is ignored
  264. **              everywhere except inside quotes, so the following
  265. **              examples are equal:
  266. **
  267. **                      name=value,foo=bar
  268. **                       name="value",foo="bar"
  269. **                        name = value ,  foo = bar
  270. **                         name = "value" ,  foo = "bar"
  271. **
  272. ** ON EXIT:
  273. **      returns a list of name-value pairs (actually HTAssocList*).
  274. **              For items with no name, just value, the name is
  275. **              the number of order number of that item. E.g.
  276. **              "1" for the first, etc.
  277. */
  278. PUBLIC HTList *HTAA_parseArgList PARAMS((char * str));
  279.  
  280. /*
  281.  
  282. Header Line Reader
  283.  
  284.  */
  285.  
  286. /* PUBLIC                                               HTAA_setupReader()
  287. **              SET UP HEADER LINE READER, i.e. give
  288. **              the already-read-but-not-yet-processed
  289. **              buffer of text to be read before more
  290. **              is read from the socket.
  291. ** ON ENTRY:
  292. **      start_of_headers is a pointer to a buffer containing
  293. **                      the beginning of the header lines
  294. **                      (rest will be read from a socket).
  295. **      length          is the number of valid characters in
  296. **                      'start_of_headers' buffer.
  297. **      soc             is the socket to use when start_of_headers
  298. **                      buffer is used up.
  299. ** ON EXIT:
  300. **      returns         nothing.
  301. **                      Subsequent calls to HTAA_getUnfoldedLine()
  302. **                      will use this buffer first and then
  303. **                      proceed to read from socket.
  304. */
  305. PUBLIC void HTAA_setupReader PARAMS((char *     start_of_headers,
  306.                                      int        length,
  307.                                      int        soc));
  308.  
  309.  
  310. /* PUBLIC                                               HTAA_getUnfoldedLine()
  311. **              READ AN UNFOLDED HEADER LINE FROM SOCKET
  312. ** ON ENTRY:
  313. **      HTAA_setupReader must absolutely be called before
  314. **      this function to set up internal buffer.
  315. **
  316. ** ON EXIT:
  317. **      returns a newly-allocated character string representing
  318. **              the read line.  The line is unfolded, i.e.
  319. **              lines that begin with whitespace are appended
  320. **              to current line.  E.g.
  321. **
  322. **                      Field-Name: Blaa-Blaa
  323. **                       This-Is-A-Continuation-Line
  324. **                       Here-Is_Another
  325. **
  326. **              is seen by the caller as:
  327. **
  328. **      Field-Name: Blaa-Blaa This-Is-A-Continuation-Line Here-Is_Another
  329. **
  330. */
  331. PUBLIC char *HTAA_getUnfoldedLine NOPARAMS;
  332.  
  333. #endif  /* NOT HTAAUTIL_H */
  334. /*
  335.  
  336.    End of file HTAAUtil.h. */
  337.